Reads a delimited text file into a data_table.
The file is read from disk with a single operation and parsed in memory. Rows may end with LF, CRLF, or CR, and a leading UTF-8 byte order mark is ignored. Rows containing only spaces and tabs are skipped. Unquoted fields are trimmed of surrounding spaces and tabs (unless the delimiter is itself a space or tab). Fields may be enclosed in double quotes to embed delimiters, line breaks, or quote characters (written as two consecutive quotes); quoting does not affect type inference. Consecutive delimiters denote an empty, or missing, field. Rows with fewer fields than the table has columns are padded with missing values.
The type of each column is inferred from its non-empty entries:
logical_column: every entry is one of T, F, TRUE, FALSE, .T., .F., .TRUE., or .FALSE. (case-insensitive) and nothing is missing.
integer_column: every entry is an integer representable as a 32-bit integer and nothing is missing.
real_column: every entry is numeric (including NaN, Inf, and Infinity), integers are mixed with reals or are missing values, or the column is entirely empty. Missing entries are stored as NaN.
string_column: any other column, including logical columns with missing entries and columns mixing logical and numeric entries. Missing entries are stored as empty strings.
The following errors terminate the program via error stop:
FS_INVALID_INPUT_ERROR: the file cannot be opened or read, the delimiter is invalid, header_row is negative, the header row is blank or beyond the end of the file, or a quoted field is unterminated or followed by text other than a delimiter.
FS_ARRAY_SIZE_ERROR: a data row holds more fields than the header row.
FS_MEMORY_ERROR: the file exceeds 2^31 - 1 bytes.
| Type | Intent | Optional | Attributes | Name | ||
|---|---|---|---|---|---|---|
| character(len=*), | intent(in) | :: | fname |
The name of the file to read. |
||
| type(data_table), | intent(out) | :: | table |
The resulting data_table, holding one column per field. |
||
| character(len=1), | intent(in), | optional | :: | delimiter |
The field delimiter. The default is a comma. The delimiter must not be a double quote, carriage return, or line feed. |
|
| integer(kind=int32), | intent(in), | optional | :: | header_row |
The one-based row, counting blank rows, holding the column names. Rows above the header are ignored, and data begins on the row after the header. The default is 1. Use 0 for files without a header; the columns are then named column_1, column_2, and so on, and the column count is the largest number of fields found in any row. |